Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle® Database XML Java API Reference 10g Release 2 (10.2) B14293-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.xml.bind
Interface Marshaller

public interface Marshaller

The `Marshaller` class is responsible for governing the process of serializing Java content trees back into XML data. It provides the basic marshalling methods:

Assume the following setup code in all following code fragments:

           JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
           Unmarshaller u = jc.createUnmarshaller();
           FooObject obj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
           Marshaller m = jc.createMarshaller();

Marshalling to a File:

           OutputStream os = new FileOutputStream( "nosferatu.xml" );
           m.marshal( obj, os );

Marshalling to a SAX ContentHandler:

           // assume MyContentHandler instanceof ContentHandler
           m.marshal( obj, new MyContentHandler() );

Marshalling to a DOM Node:

           DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
           dbf.setNamespaceAware(true);
           DocumentBuilder db = dbf.newDocumentBuilder();
           Document doc = db.newDocument();

           m.marshal( obj, doc );

Marshalling to a java.io.OutputStream:

           m.marshal( obj, System.out );

Marshalling to a java.io.Writer:

           m.marshal( obj, new PrintWriter( System.out ) );

Marshalling to a javax.xml.transform.SAXResult:

           // assume MyContentHandler instanceof ContentHandler
           SAXResult result = new SAXResult( new MyContentHandler() );

           m.marshal( obj, result );

Marshalling to a javax.xml.transform.DOMResult:

           DOMResult result = new DOMResult();

           m.marshal( obj, result );

Marshalling to a javax.xml.transform.StreamResult:

           StreamResult result = new StreamResult( System.out );

           m.marshal( obj, result );

Marshalling `java.lang.Object` Objects

Although each of the marshal methods accepts a `java.lang.Object` as its first parameter, JAXB Providers are not required to be able to marshal any arbitrary `java.lang.Object`. If the `JAXBContext` object that was used to create this `Marshaller` does not have enough information to know how to marshal the object parameter (or any objects reachable from it), then the marshal operation will throw a `MarshalException`. Even though JAXB Providers are not required to be able to marshal arbitrary `java.lang.Object` objects, some providers may allow it.

Encoding

By default, the Marshaller will use UTF-8 encoding when generating XML data to a `java.io.File`, `java.io.OutputStream`, and `java.io.Writer`. Use the `setProperty` API to change the ouput encoding used during these marshal operations.

Validation and Well-Formedness

Client applications are not required to validate the Java content tree prior to calling any of the marshal API's. Furthermore, there is no requirement that the Java content tree be valid with respect to its original schema in order to marshal it back into XML data. Different JAXB Providers will support marshalling invalid Java content trees at varying levels, however all JAXB Providers must be able to marshal a valid content tree back to XML data. A JAXB Provider must throw a `MarshalException` when it is unable to complete the marshal operation due to invalid content. Some JAXB Providers will fully allow marshalling invalid content, others will fail on the first validation error.

Although there is no way to enable validation during the marshal operation, it is possible that certain types of validation events will be detected during the operation. These events will be reported to the registered event handler. If the client application has not registered an event handler prior to invoking one of the marshal API's, then events will be delivered to the default event handler which will terminate the marshal operation after encountering the first error or fatal error.

Supported Properties

`jaxb.encoding`
  The output encoding to use when marshalling the XML data. The Marshaller will use "UTF-8" by default if this property is not specified.
`jaxb.formatted.output`
  This property controls whether or not the Marshaller will format the resulting XML data with line breaks and indentation. A true value for this property indicates human readable indented xml data, while a false value indicates unformatted xml data. The Marshaller will default to false (unformatted) if this property is not specified.
`jaxb.schemaLocation`
  This property allows the client application to specify an xsi:schemaLocation attribute in the generated XML data. The format of the schemaLocation attribute value is discussed in an easy to understand, non-normative form in Section 5.6 of the W3C XML Schema Part 0: Primer and specified in Section 2.6 of the W3C XML Schema Part 1: Structures.
`jaxb.noNamespaceSchemaLocation`
  This property allows the client application to specify an xsi:noNamespaceSchemaLocation attribute in the generated XML data. The format of the schemaLocation attribute value is discussed in an easy to understand, non-normative form in Section 5.6 of the W3C XML Schema Part 0: Primer and specified in Section 2.6 of the W3C XML Schema Part 1: Structures.

Encoding Parameter Name

JAXB Providers must convert the encoding parameter to its canonical form as defined by the IANA Charset Registry. Some character sets have a historical name that is defined for compatibility with previous versions of the Java platform. These historical names must not be used since they may violate the W3C XML v1.0 Recommendation requirements for valid encoding names. In some cases, the historical name is the same as the canonical name, but not always. The client application should be allowed to specify the encoding using any of the available aliases for that charset (For example, "UTF8" and "UTF-8" should both resolve to the canonical name for this encoding which is "UTF-8". However, the historical name is "UTF8", which should not be used by providers).

Please refer to the javadocs for java.nio.charset.Charset for more details.

Since:
  JAXB1.0
See Also:
  `JAXBContext`, `Validator`, `Unmarshaller`

Field Summary
`static java.lang.String` | `JAXB_ENCODING` The name of the property used to specify the output encoding in the marshalled XML data.
`static java.lang.String` | `JAXB_FORMATTED_OUTPUT` The name of the property used to specify whether or not the marshalled XML data is formated with linefeeds and indentation.
`static java.lang.String` | `JAXB_NONAMESPACESCHEMALOCATION` The name of the property used to specify the the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.
`static java.lang.String` | `JAXB_SCHEMALOCATION` The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.

Method Summary
`ValidationEventHandler` | `getEventHandler()` Return the current event handler or the default event handler if one hasn't been set.
`java.lang.Object` | `getProperty(java.lang.String name)` Get the particular property in the underlying implementation of `Marshaller`.
`void` | `marshal(java.lang.Object obj, ContentHandler handler)` Marshal the content tree rooted at obj into SAX2 events.
`void` | `marshal(java.lang.Object obj, Node node)` Marshal the content tree rooted at obj into a DOM tree.
`void` | `marshal(java.lang.Object obj, java.io.OutputStream os)` Marshal the content tree rooted at obj into an output stream.
`void` | `marshal(java.lang.Object obj, Result result)` Marshal the content tree rooted at obj into the specified `javax.xml.transform.Result`.
`void` | `marshal(java.lang.Object obj, java.io.Writer writer)` Marshal the content tree rooted at obj into a Writer.
`void` | `setEventHandler(ValidationEventHandler handler)` Allow an application to register a validation event handler.
`void` | `setProperty(java.lang.String name, java.lang.Object value)` Set the particular property in the underlying implementation of `Marshaller`.

Field Detail

### JAXB_ENCODING

    public static final java.lang.String JAXB_ENCODING

  The name of the property used to specify the output encoding in the marshalled XML data.
  See Also:
    Constant Field Values

### JAXB_FORMATTED_OUTPUT

    public static final java.lang.String JAXB_FORMATTED_OUTPUT

  The name of the property used to specify whether or not the marshalled XML data is formated with linefeeds and indentation.
  See Also:
    Constant Field Values

### JAXB_SCHEMALOCATION

    public static final java.lang.String JAXB_SCHEMALOCATION

  The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.
  See Also:
    Constant Field Values

### JAXB_NONAMESPACESCHEMALOCATION

    public static final java.lang.String JAXB_NONAMESPACESCHEMALOCATION

  The name of the property used to specify the the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.
  See Also:
    Constant Field Values

Method Detail

### marshal

    public void marshal(java.lang.Object obj,
                        Result result)
                 throws JAXBException

  Marshal the content tree rooted at obj into the specified `javax.xml.transform.Result`.

  All JAXB Providers must at least support `DOMResult`, `SAXResult`, and `StreamResult`. It can support other derived classes of `Result` as well.

  Parameters:
    `obj` - The content tree to be marshalled.
    `result` - XML will be sent to this Result
  Throws:
    `JAXBException` - If any unexpected problem occurs during the marshalling.
    `MarshalException` - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

### marshal

    public void marshal(java.lang.Object obj,
                        java.io.OutputStream os)
                 throws JAXBException

  Marshal the content tree rooted at obj into an output stream.
  Parameters:
    `obj` - The content tree to be marshalled.
    `os` - XML will be added to this stream.
  Throws:
    `JAXBException` - If any unexpected problem occurs during the marshalling.
    `MarshalException` - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

### marshal

    public void marshal(java.lang.Object obj,
                        java.io.Writer writer)
                 throws JAXBException

  Marshal the content tree rooted at obj into a Writer.
  Parameters:
    `obj` - The content tree to be marshalled.
    `writer` - XML will be sent to this writer.
  Throws:
    `JAXBException` - If any unexpected problem occurs during the marshalling.
    `MarshalException` - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

### marshal

    public void marshal(java.lang.Object obj,
                        ContentHandler handler)
                 throws JAXBException

  Marshal the content tree rooted at obj into SAX2 events.
  Parameters:
    `obj` - The content tree to be marshalled.
    `handler` - XML will be sent to this handler as SAX2 events.
  Throws:
    `JAXBException` - If any unexpected problem occurs during the marshalling.
    `MarshalException` - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

### marshal

    public void marshal(java.lang.Object obj,
                        Node node)
                 throws JAXBException

  Marshal the content tree rooted at obj into a DOM tree.
  Parameters:
    `obj` - The content tree to be marshalled.
    `node` - DOM nodes will be added as children of this node. This parameter must be a Node that accepts children (`Document`, `DocumentFragment`, or `Element`)
  Throws:
    `JAXBException` - If any unexpected problem occurs during the marshalling.
    `MarshalException` - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

### setProperty

    public void setProperty(java.lang.String name,
                            java.lang.Object value)
                     throws PropertyException

  Set the particular property in the underlying implementation of `Marshaller`. See Supported Properties .
  Parameters:
    `name` - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
    `value` - the value of the property to be set
  Throws:
    `PropertyException` - when there is an error processing the given property or value

### getProperty

    public java.lang.Object getProperty(java.lang.String name)
                                 throws PropertyException

  Get the particular property in the underlying implementation of `Marshaller`. See Supported Properties .
  Parameters:
    `name` - the name of the property to retrieve
  Returns:
    the value of the requested property
  Throws:
    `PropertyException` - when there is an error retrieving the given property or value property name

### setEventHandler

    public void setEventHandler(ValidationEventHandler handler)
                         throws JAXBException

  Allow an application to register a validation event handler.

  The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the marshal API's. If the client application does not register a validation event handler before invoking one of the marshal methods, then validation events will be handled by the default event handler which will terminate the marshal operation after the first error or fatal error is encountered.

  Parameters:
    `handler` - the validation event handler
  Throws:
    `JAXBException` - if an error was encountered while setting the event handler

### getEventHandler

    public ValidationEventHandler getEventHandler()
                                           throws JAXBException

  Return the current event handler or the default event handler if one hasn't been set.
  Returns:
    the current ValidationEventHandler or the default event handler if it hasn't been set
  Throws:
    `JAXBException` - if an error was encountered while getting the current event handler

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle® Database XML Java API Reference 10g Release 2 (10.2) B14293-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001 Sun Microsystems, Inc. All rights reserved.